home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 126-150 / scopedisk127 / gshell / gshell1.3 / gshell.doc < prev    next >
Text File  |  1995-03-19  |  22KB  |  491 lines
  1.  
  2.                GShell - The CLI User's Directory Utility
  3.  
  4.                              Version 1.3
  5.                   Copyright © 1990 Thomas Krehbiel
  6.                           All Rights Reserved
  7.  
  8.                         Released May 15, 1990
  9.  
  10.              +-----------------------------------------+
  11.              | NOTE: Requires Arp.library release 1.3! |
  12.              +-----------------------------------------+
  13.  
  14. This program is NOT public domain, but may be freely distributed as long as
  15. 1) No fee is charged for said distribution, except for reasonable media
  16. costs, and 2) all files in the archive remain together.  It is being
  17. released "as is", with no warranty expressed or implied as to the use or
  18. misuse of the program.
  19.  
  20. As this is the first released version, there ARE going to be bugs.
  21. Instead of fuming about them, tell me about them and I will try to fix
  22. them.  Also, suggestions for improvements are also welcome, as long as
  23. they fit somewhat within the program guidelines below.
  24.  
  25. Files in the archive:
  26.  
  27.      GShell                   The program.
  28.      GShell.info              And its icon.
  29.      GShell.pic               A diagram of where all the gadgets are.
  30.      GShell.doc               This document.
  31.      GShell.config            Sample configuration file.
  32.      README                   Latest release notes.
  33.  
  34.  
  35. REVISION HISTORY
  36. ~~~~~~~~~~~~~~~~
  37.  
  38. NOTE:  Anything marked with a double-asterisk (**) denotes a new feature.
  39.        So if you're a GShell veteran, scan the revision list below, then
  40.        just search for "**" in your favorite editor to find the new stuff.
  41.  
  42. Version   Date           Comments
  43. -------   -----------    ---------------------------------------------------
  44. 1.3       14-May-90      Some bug fixes and new features from 1.2.
  45.                          Went to using Arp's ASyncRun() for programs, fixing
  46.                           a couple of bugs that cropped up on my system.
  47.                          Added the StackSize specification for programs.
  48.                          Can work with destination directory, now, too (!).
  49.                          More new template args (see below).
  50.                          Added the "H" gadget flag.
  51.                          Changed meaning of the FLIP gadget.
  52.  
  53. 1.2       05-May-90      Mostly Bug fixes to version 1.1.
  54.                          Fixed a Parent Gadget bug.
  55.                          Fixed "65575 directories" bug.
  56.                          Fixed problem of quoting filenames with spaces.
  57.                          Added new template args (see below).
  58.                          Removed the %/ template arg (not necessary now).
  59.                          Added the Debug configuration keyword.
  60.  
  61. 1.1       01-May-90      First released to general public.
  62.                          Now works from Workbench (good idea!).
  63.                          Added a NOFILES gadget flag.
  64.                          Various bug fixes.
  65.  
  66. 1.0       15-Feb-90      Initial version (not released).
  67.  
  68.  
  69. INTRODUCTION
  70. ~~~~~~~~~~~~
  71. GShell, put simply, is another directory utility.  Before you groan
  72. and roll you eyes and delete it in disgust, though, read a little further.
  73.  
  74. I had been looking around the Amiga PD community for a directory
  75. utility type of program that would suit my needs.  What I did NOT need:
  76.  
  77.      * I did NOT want to avoid using CLI (since I can type just fine).
  78.      * I did NOT want it to have so many gadgets that it was confusing.
  79.      * I did NOT want to be locked into the programmer's selection of
  80.        said gadgets.
  81.      * I did NOT want the program to be a million bytes long.
  82.  
  83. What I DID want:
  84.  
  85.      * I wanted a program that was TOTALLY configurable.
  86.      * I wanted a program that had few built-in commands, but instead called
  87.        on external programs to do stuff like copying, renaming, etc. (because
  88.        I do use CLI a LOT, I have amassed a bunch of CLI programs that I like,
  89.        and why should my GShell do something these programs already do?).
  90.      * I wanted to have my choice of the information displayed about the
  91.        files.
  92.  
  93. So, in order to get the 'perfect' program, I wrote my own.
  94.  
  95.  
  96. REQUIREMENTS
  97. ~~~~~~~~~~~~
  98. This program requires Arp.library release 1.3.  My reasons for
  99. relying heavily on this library are:  1) It made programming a LOT
  100. easier and faster; 2) I wanted to support the Arp 'movement';
  101. 3) WB 2.0 will undoubtedly have a library very much like it if and when
  102. it is released.
  103.  
  104. If you do not have the library, then I STRONGLY urge you to get
  105. it.  It is probably available on a BBS near you.  All you need is
  106. the library, not the commands.
  107.  
  108.  
  109. RUNNING GSHELL
  110. ~~~~~~~~~~~~~~
  111. To run GShell from Workbench, just double-click its icon.
  112.  
  113. To run GShell from the CLI, use the following syntax:
  114.  
  115. 1> GShell [sourceDir] [destDir]
  116.  
  117. where 'sourceDir' is an optional source directory, and 'destDir' is
  118. an optional destination directory.
  119.  
  120.  
  121. WHAT YOU SEE
  122. ~~~~~~~~~~~~
  123. Since you have not defined a configuration file, you should see GShell come
  124. up in its default state.  Refer to the accompanying IFF diagram for where
  125. the gadget positions are.  Roughly in a clockwise order, here is the display:
  126.  
  127.    Close Box         Hmmm...  If you don't this one by now...
  128.  
  129.    Title Bar         Tells whether you are currently viewing the Source
  130.                      Directory, Destination Directory, or Volume List.
  131.  
  132.    Depth Gadgets     Another tough one, here.
  133.  
  134.    Scroll Bar        Scrolls through the list of filenames or devices.  It
  135.                      is an active scroll bar so you can drag it and see things
  136.                      happening in the window.
  137.  
  138.    Arrow Gadgets     Same as the scroll bar, only one file at a time.  They
  139.                      repeat when you hold them down, too.
  140.  
  141.    Directory Name    The string gadget right in the middle holds the name of
  142.                      the directory you're looking at.  You can click here and
  143.                      just type in a new directory if you want.
  144.  
  145.    Parent Gadget     The left-pointing arrow just to the left of the Directory
  146.                      Name will attempt to move you to the parent of the
  147.                      current directory.
  148.  
  149.    SET               Will highlight all files in the displayed directory.
  150.  
  151.    RESET             Will un-highlight all files in the displayed directory.
  152.  
  153. *  FLIP              This gadget's function has changed in GShell 1.3.  Now
  154. *                    it exchanges the Source and Destination directories (ie.
  155. *                    the Source becomes the Destination and vice versa).  Note
  156. *                    that this is different from the action of the right mouse
  157. *                    button.
  158.  
  159.    BYTES             Will calculate the number of bytes used in all highlighted
  160.                      files and directories.  It is recursive, so it will search
  161.                      down through directory paths to find the size of all files
  162.                      in all directory paths.
  163.  
  164.    VOL               Changes the display to the Volume/Device List display.
  165.                      From this list you can double-click on any volume to
  166.                      read it into the display.
  167.  
  168.    Sizing Gadget     Sometimes hidden down in the lower right is the window
  169.                      sizing gadget.  You can make the window bigger to display
  170.                      more information about the files like date of creation,
  171.                      protection bits, etc.  Also making the window bigger allows
  172.                      more files to be displayed in the file area.
  173.  
  174.  
  175. SOURCE VS. DESTINATION DIRECTORIES
  176. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  177.    GShell has two directories you can access.  The Source Directory is where
  178. most of the action will probably take place.  The Destination Directory is
  179. usually only used for copying and moving files.
  180.  
  181.    To toggle between the two directories, click the right mouse button once.
  182.  
  183. ** As of version 1.3, GShell does not make as big of a distinction between the
  184. ** source and destination directories.  In previous version, commands would
  185. ** only work on the source directory, but now you can work with either the
  186. ** source or the destination directory.  For example, you can copy files from
  187. ** the source to the destination, switch to the destination directory with the
  188. ** right mouse button, then select some files and rename them (or whatever).
  189.  
  190.    To enter a sub-directory on the display, just double-click on the
  191. directory name.
  192.  
  193.  
  194. CONFIGURATION
  195. ~~~~~~~~~~~~~
  196.    You will notice that there are no gadgets defined in the bottom portion
  197. of the window.  This is because you have not told GShell what you want to
  198. put there.  GShell has three types of gadgets:  Internal Gadgets which are
  199. hard-coded into the program (like the BYTES and VOL gadgets), User Volume
  200. Gadgets, and User Program Gadgets.
  201.  
  202.    GShell looks for a file called "S:GShell.Config" to read the configuration.
  203. This file contains information about colors, default startup directories,
  204. gadget meanings, and other things.  Here is a sample configuration file:
  205.  
  206. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  207. ; Sample configuration file for GShell.
  208.  
  209. Width       305
  210.  
  211. DefSource   Work:
  212. DefDest     RAM:
  213. CLIWindow   NEWCON:0/11/640/189/MyWindow
  214.  
  215. ;        Row   GadText  Flags Program        ArgTemp     AskTemp     MaxFiles
  216.  
  217. Gadget   1     DF0:     V     DF0:
  218. Gadget   1     DF1:     V     DF1:
  219.  
  220. Gadget   2     Copy     EDU   C:Copy         "%h %df"    ""                0
  221. Gadget   2     Del      ESUF  C:Delete       "%h"        ""                0
  222. Gadget   2     Renam    EASU  C:Rename       "%h %su"    "Rename %f to?"   0
  223.  
  224. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  225.  
  226.    Notice that blank lines and lines beginning with semi-colons (;) are ignored
  227. by GShell.  Each line begins with a keyword, and is following by one or more
  228. arguments for that keyword.  Keywords may be upper or lower case, or any
  229. combination thereof.  Arguments must be seperated by at least one space or
  230. tab, and any arguments that contain a space or tab must be enclosed in double
  231. quotes (").  To insert a null arguments, use two double-quotes ("") as with
  232. the Copy and Del gadgets in the above example.
  233.  
  234.    Here is a list of the keywords that GShell recognizes:
  235.  
  236.             Min/Max
  237. KeyWord     Args        Description
  238. -------     --------    -----------------------------------------------
  239. Gadget      4/7         Defines a User Volume or User Program gadget.
  240. DefSource   1/1         Sets the default startup Source Directory.
  241. DefDest     1/1         Sets the default startup Destination Directory.
  242. LeftEdge    1/1         Sets the window's initial LeftEdge position.
  243. TopEdge     1/1         Sets the window's initial TopEdge position.
  244. Width       1/1         Sets the window's initial Width.
  245. Height      1/1         Sets the window's initial Height.
  246. CLIWindow   1/1         Defines the console window used for some commands.
  247. FileTemp    1/1         Defines the template used to show filenames.
  248. DirTemp     1/1         Defines the template used to show directories.
  249. DevTemp     1/1         Defines the template used to show devices.
  250. AsnTemp     1/1         Defines the template used to show assigns.
  251. WBackPen    1/1         Pen number for window background (def BLUE).
  252. LBackPen    1/1         Pen number for dir list background (def BLACK).
  253. CBackPen    1/1         Pen for command background (def WHITE).
  254. MBackPen    1/1         Pen for message background (def WHITE).
  255. GBackPen    1/1         Pen for gadget background (def BLUE).
  256. FilePen     1/1         Pen to render filenames (def WHITE).
  257. DirPen      1/1         Pen to render directories (def BLUE).
  258. DevPen      1/1         Pen to render devices (def WHITE).
  259. AsnPen      1/1         Pen to render assigns (def WHITE).
  260. UserPen     1/1         Pen to render user gadget names (def WHITE).
  261. IntPen      1/1         Pen to render built-in gadget names (def BLACK).
  262. LBordPen    1/1         Pen to render dir list border (def WHITE).
  263. DBordPen    1/1         Pen to render dir name border (def BLACK).
  264. GBordPen    1/1         Pen to render gadget borders (def BLACK).
  265. FHighPen    1/1         Pen to highlight filenames (def RED).
  266. DHighPen    1/1         Pen to highlight directoies (def RED).
  267. VHighPen    1/1         Pen to highlight devices (def RED).
  268. AHighPen    1/1         Pen to highlight assigns (def RED).
  269. MsgPen      1/1         Pen to render messages (def BLACK).
  270. Debug       0/0         Sends debugging information to CLI window.
  271.  
  272.  
  273. KEYWORD:  Gadget
  274. ~~~~~~~~~~~~~~~~
  275.    The Gadget keyword deserves further explanation.  Here is the syntax of
  276. the Gadget keyword:
  277.  
  278.    GADGET <Row> <GadText> <Flags> <Program> [ArgTemp] [AskTemp] [MaxFiles] [StackSize]
  279.  
  280.    Where:
  281.  
  282.       Row         This is the row number that the gadget will show up on,
  283.                   starting with row number 1 being the row directly under
  284.                   the built-in gadgets and working down.
  285.  
  286.       GadText     The text that will appear inside the gadget on the window.
  287.  
  288.       Flags       This defines what action takes place when the gadget is
  289.                   pressed (see below).  It is a string of characters, each
  290.                   of which represents something to be done.
  291.  
  292.       Program     This is either the pathname of a program to run when the
  293.                   gadget is clicked (for User Program Gadgets) or the
  294.                   name of device to go to (for User Volume Gadgets), depending
  295.                   on the Flags settings.  For programs, it is best to specify
  296.                   a full pathname (ie. "Sys:Tools/ShowANIM" as opposed to just
  297.                   "ShowANIM").
  298.  
  299.       ArgTemp     This string specifies how the arguments for the command
  300.                   are given (see below).  It serves as a template, into
  301.                   which highlighted filenames go, etc.  If not specified,
  302.                   then no arguments are used.
  303.  
  304.       AskTemp     This string is the template to use in asking the user
  305.                   for information (see below).  It can be left null ("") if
  306.                   it is not required.
  307.  
  308.       MaxFiles    Specifies the maximum number of files that the Program
  309.                   can accomodate in its command line.
  310.  
  311. **    StackSize   This specifies the stack size to use when running the
  312.                   program.  If you specify zero (0), then the default of
  313.                   4096 is used.  Otherwise, this should be an integer
  314.                   between 0 and whatever (should be an even number, though).
  315.                   This is useful for programs that need a BIG stack to run.
  316.  
  317.  
  318. Gadget Templates
  319. ~~~~~~~~~~~~~~~~
  320.    Here is the format for the ArgTemp and AskTemp template strings.  The format
  321. is loosely based on the C Language printf() function, so if you are familiar
  322. with that then you should pick this up pretty quickly.  First, an example:
  323.  
  324.       %h TO %D
  325.  
  326.    This is the argument template string typically used for a Copy command.
  327. GShell looks through the string for percent signs (%), which tell it to replace
  328. this embedded command with a string.  Here are the recognized embedded commands:
  329.  
  330.       %h          Replace with current highlighted pathname.
  331.       %f          Replace with current highlighted filename only (not path).
  332.       %s          Replace with name of source directory.
  333.       %d          Replace with name of destination directory.
  334. **    %a          Replace with name of ACTIVE directory (source or destination).
  335.       %u          Replace with user input text from Ask.
  336.       %sf         Replace with source directory + highlighted filename.
  337.       %df         Replace with destination directory + highlighted filename.
  338. **    %af         Replace with ACTIVE directory + highlighted filename.
  339.       %su         Replace with source directory + user input text.
  340.       %du         Replace with destination directory + user input text.
  341. **    %au         Replace with ACTIVE directory + user input text.
  342.       %uq         Replace with user input text and quote as a filename.
  343.       %%          Used to insert a percent sign in the argument list.
  344.  
  345.    So for the above example, if the filename highlighted is FooBar, the source
  346. directory is DF0:Junk, and the destination directory is DF1:, here is what
  347. GShell would do with the template "%h TO %D":
  348.  
  349.    DF0:Junk/FooBar TO DF1:FooBar
  350.  
  351.  
  352. Gadget Flags
  353. ~~~~~~~~~~~~
  354.    Here are the different flags available which define the type of gadget:
  355.  
  356.       E        If specified, will run the program once for each highlighted
  357.                filename.  If not specified, then the program will only be
  358.                run once with all highlighted filenames (up to the maximum
  359.                set by MaxFiles) as the argument.  This option is for commands
  360.                (like Copy) that only accept one filename as an argument.
  361.  
  362.       S        If specified, GShell will re-read the source directory after
  363.                all commands are finished.  Useful if you are moving files
  364.                out of the source directory.
  365.  
  366.       B        Not implemented.  Will run program as a background task.
  367.  
  368.       C        Create a CLI output window for the command.  If not specified,
  369.                then all output goes to NIL: (oblivion) and some programs
  370.                might actually crash.  This is useful for programs like Info
  371.                that send the info to the CLI window.
  372.  
  373.       A        Ask user for information.  Will pop up a requester with the
  374.                AskTemp string as the question and wait for a string gadget
  375.                response from the user.
  376.  
  377.       O        If this is specified, then the Ask requester (if specified)
  378.                will only appear once at the beginning of a (possibly) long
  379.                list of highlighted filenames.  If not specified, then the
  380.                Ask requester will pop up for each and every highlighted
  381.                filename.
  382.  
  383.       F        Ask user for verification before doing the operation.  Puts
  384.                up a requester saying "Are you sure?" before proceeding.
  385.                You'd usually want to do this for a delete operation, I would
  386.                think.
  387.  
  388.       V        This tells GShell that this gadget is really a User Volume
  389.                Gadget.  If this is the case, then the ProgramName is
  390.                actually the name of a device which GShell will make the
  391.                current directory when this gadget is clicked.
  392.  
  393.       U        If set, GShell will unhighlight each highlighted file that
  394.                is used after the command is finished.  Otherwise, files
  395.                will remain highlighted.
  396.  
  397.       D        If specified, GShell will re-read the destination directory
  398.                once the operation is finished.  This would be useful for
  399.                copy or move type of commands, or anytime the destination
  400.                is modified.
  401.  
  402.       W        This will tell GShell to put a "Press RETURN To Continue" message
  403.                in a CLI window before closing it so that the user can see
  404.                the output from the command at his leisure.
  405.  
  406.       N        This tells GShell that this gadget does not need any files
  407.                highlighted in order to work.  Normally if no files are
  408.                highlighted, GShell will complain.  But not so with this
  409.                handy-dandy flag.
  410.  
  411. **    H        Tells GShell to re-read either the Source or the Destination
  412.                directories, depending on which is currently active.  That is,
  413.                it will re-read the active directory when the operation is
  414.                finished.
  415.  
  416.  
  417. KEYWORDS:  FileTemp, DirTemp, DevTemp, AsnTemp
  418. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  419.      Another area where GShell may be configured is in what is displayed in
  420. the file area.  Four user-definable templates are used to determine this, and
  421. are specified with the FileTemp, DirTemp, DevTemp, and AsnTemp keywords and
  422. affect filename entries, directory entries, device entries, and assign entries
  423. respectively.
  424.  
  425.      These templates are similar in format to the Gadget Templates, above
  426. only they use different embedded commands.  Here is a list of the ones GShell
  427. currently recognizes:
  428.  
  429.      %e        Filename, directory name, device name, or assigned name [25].
  430.      %b        Number of bytes in a file only [7].
  431.      %y        Day of file or directory creation (Mon, Tue, etc.) [3].
  432.      %t1       Time in format HH:MM (24 hour) [5].
  433.      %t2       Time in format HH:MMa (12 hour) [6].
  434.      %t3       Time in format HH:MM:SS (24 hour) [8].
  435.      %t4       Time in format HH:MM:SSa (12 hour) [9].
  436.      %d1       Date in format DD/MM/YY [8].
  437.      %d2       Date in format MM/DD/YY [8].
  438.      %d3       Date in format DD-Mon-YY [9].
  439.      %p        Protection bits for files or directories [8].
  440.      %a        Physical path to a logical assigned name [40].
  441.  
  442.      NOTE:  Using the "%a" option slows things down considerably.
  443.  
  444.      NOTE:  The number in brackets is the number of character positions that
  445. that particular option uses.
  446.  
  447.      Here is a list of the four default templates:
  448.  
  449.           FileTemp       "%e %b %p %y %d1 %t2"
  450.           DirTemp        "%e   [DIR] %p %y %d1 %t2"
  451.           DevTemp        "%e   [DEV]"
  452.           AsnTemp        "%e [ASSGN]"
  453.  
  454.  
  455. KEYWORD:  Debug
  456. ~~~~~~~~~~~~~~~
  457.      This allows you to find out exactly what GShell is trying to do when
  458. you select a gadget.  If you run GShell from the CLI, and you specify this
  459. keyword, then GShell will print the exact string it is trying to execute to
  460. the CLI window before it attempts executes it.  This is useful to see if you
  461. have built your argument template correctly.  Note that this option is
  462. currently useless from Workbench.
  463.  
  464.  
  465. CONCLUSION
  466. ~~~~~~~~~~
  467.      Look at the supplied sample Config file (GShell.Config) for examples
  468. of most all of the above templates, keywords, etc.  You can just modify this
  469. one to correct for your own paths and programs and copy to your S: directory
  470. to use.
  471.  
  472.      There are a few things I would like to do to this program in the future,
  473. like add an Arexx port, be able to use a custom screen with interlace, add
  474. keyboard equivalents for gadgets, and some other junk.
  475.  
  476.      Hope this program finds a use someplace.  Have fun with it!
  477.  
  478.  
  479. THE AUTHOR
  480. ~~~~~~~~~~
  481.      Thomas Krehbiel
  482.      10747 Surry Road
  483.      Chester, VA  23831
  484.  
  485.      I can also be reached on the Amiga Blues BBS (804-796-3631) as
  486. "Tom Krehbiel".  The Blues has now become a pay BBS ($10/year), but it is
  487. well worth the money (your welcome, Jake!).
  488.  
  489.                                              Tom
  490.  
  491.